Portlet 2.0 Schema

To have access to the latest Portlet 2.0 spec features, such as Events and Public Render Parameters, it's important to ensure that your portlet.xml contains the following schema definition:

<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd"
  version="2.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd">

Preserving Request Parameters outside ActionRequest

By default the Portlet Bridge does not retain any Request Parameters that were received as part of an ActionRequest from the Portal. To ensure that Request Parameters from an ActionRequest are retained in the Bridge Request Scope until a RenderRequest, add the following init-param to portlet.xml:

<init-param>
  <name>javax.portlet.faces.preserveActionParams</name>
  <value>true</value>
</init-param>

If you're using Facelets:

Include the following in web.xml:

<context-param>
  <param-name>javax.portlet.faces.RENDER_POLICY</param-name>
  <param-value>ALWAYS_DELEGATE</param-value>
</context-param>

If you're using JSP:

Include the following in web.xml:

<context-param>
  <param-name>javax.portlet.faces.RENDER_POLICY</param-name>
  <param-value>NEVER_DELEGATE</param-value>
</context-param>

Supported Render Policies in Portlet Bridge:

• ALWAYS_DELEGATE: Indicates the Bridge should not render the view itself but rather always delegate the rendering.

• NEVER_DELEGATE: Indicates the Bridge should always render the view itself and never delegate.

• DEFAULT: Directs the Bridge to first delegate the render and if and only if an Exception is thrown then render the view based on its own logic. If the configuration parameter is not present or has an invalid value the Bridge renders using default behavior. I.e. as if DEFAULT is set.

Events

<init-param>
  <name>javax.portlet.faces.autoDispatchEvents</name>
  <value>true</value>
</init-param>

<supported-publishing-event>
  <qname xmlns:jbp="urn:jboss:portal:samples:event">jbp:BookingEvent</qname>
</supported-publishing-event>

<event-definition>
  <qname xmlns:jbp="urn:jboss:portal:samples:event">jbp:BookingEvent</qname>
  <value-type>org.jboss.example.booking.BookingEvent</value-type>
</event-definition>

@XmlRootElement
public class BookingEvent implements Serializable {

  private String id;
  public static final QName QNAME = new QName("urn:jboss:portal:samples:event", "BookingEvent");

  public BookingEvent(String id) {
      this.id = id;
  }

  public String getId() {
    return id;
  }
}

Object response = FacesContext.getCurrentInstance().getExternalContext().getResponse();
  if (response instanceof StateAwareResponse) {
    String id = "an id";
    StateAwareResponse stateResponse = (StateAwareResponse) response;
    stateResponse.setEvent(BookingEvent.QNAME, new BookingEvent(id));
  }

<init-param>
  <name>javax.portlet.faces.bridgeEventHandler</name>
  <value>org.jboss.example.booking.BookingEventHandler</value>
</init-param>

<supported-processing-event>
  <qname xmlns:jbp="urn:jboss:portal:samples:event">jbp:BookingEvent</qname>
</supported-processing-event>

public class BookingEventHandler implements BridgeEventHandler {
  public EventNavigationResult handleEvent(FacesContext context, Event event) {
    // Process event payload as appropriate
  }
}

Public Render Parameters

Public Render Parameters (or PRPs) are one of the most powerful and simple Portlet 2.0 features. Several portlets (JSF or not) can share the same render parameters. This feature can be use to present a cohesive UI to the user across all portlets on the page (i.e. using an employee ID to display relative data).

<portlet>
  ...
  <supported-public-render-parameter>hotelName</supported-public-render-parameter>
</portlet>

<public-render-parameter>
  <identifier>hotelName</identifier>
  <qname xmlns:j="http://jboss.org/params">j:hotelName</qname>
</public-render-parameter>

<init-param>
  <name>javax.portlet.faces.bridgePublicRenderParameterHandler</name>
  <value>org.jboss.example.booking.BookingPRPHandler</value>
</init-param>

Object response = FacesContext.getCurrentInstance().getExternalContext().getResponse();
if (response instanceof StateAwareResponse) {
  StateAwareResponse stateResponse = (StateAwareResponse) response;
  stateResponse.setRenderParameter("hotelName", "Name of Hotel");
}

public class BookingPRP {
  private String hotelName;

  public String getHotelName() {
    return hotelName;
  }

  public void setHotelName(String hotelName) {
    this.hotelName = hotelName;
  }
}

<application>
  <application-extension>
    <bridge:public-parameter-mappings>
      <bridge:public-parameter-mapping>
        <parameter>bookingMapPortlet:hotelName</parameter>
        <model-el>#{bookingPRP.hotelName}</model-el>
      </bridge:public-parameter-mapping>
    </bridge:public-parameter-mappings>
  </application-extension>
</application>

public class BookingPRPHandler implements BridgePublicRenderParameterHandler {
  public void processUpdates(FacesContext context) {
    ELContext elContext = context.getELContext();
    BookingPRPBean bean = (BookingPRPBean) elContext.getELResolver().getValue(elContext, null, "bookingPRP");

    if(null != bean) {
      System.out.println("******processUpdates from BookingPRPHandler: " + bean.getHotelName());
    }
  }
}

Portlet Session

It's possible to share data with other portlets, within the same portlet application, using name/value pairs within the PortletSession. Use the following code to set the name/value data:

Object objSession = FacesContext.getCurrentInstance().getExternalContext().getSession(false);
  try {
    if (objSession instanceof PortletSession) {
      PortletSession portalSession = (PortletSession)objSession;
      portalSession.setAttribute("your parameter name", "parameter value", PortletSession.APPLICATION_SCOPE);
    }
  }

Then in your JSP or Facelets page you can retrieve the value using:

#{httpSessionScope['your parameter name']}

Switching Portlet Modes

A PortletMode represents a distinct render path within an application. There are three standard modes: view, edit, and help. The Bridge's ExternalContext.encodeActionURL() recognizes the query string parameter javax.portlet.faces.PortletMode and uses this parameter's value to set the portlet mode on the underlying portlet actionURL or response, but once processed it then removes this parameter from the query string.

The following navigation rule causes one to render the \edit.xhtml viewId in the portlet edit mode:

<navigation-rule>
  <from-view-id>/register.xhtml</from-view-id>
  <navigation-case>
    <from-outcome>edit</from-outcome>
    <to-view-id>/edit.xhtml?javax.portlet.faces.PortletMode=edit</to-view-id>
  </navigation-case>
</navigation-rule>

Portlet Mode's last viewId

By default a mode change will start in the mode's default view without any (prior) existing state. One common portlet pattern when returning to the mode one left after entering another mode (e.g.. view -> edit -> view) is to return to the last view (and state) of this original mode. The Bridge will explicitly encode the necessary information so that when returning to a prior mode it can target the appropriate view and restore the appropriate state. The session attributes maintained by the Bridge are intended to be used by developers to navigate back from a mode to the last location and state of a prior mode, as such a developer needs to describe a dynamic navigation: "from view X return to the last view of mode y". This is most easily expressed via an EL expression, for example:

<navigation-rule>
  <from-view-id>/edit.xhtml*</from-view-id>
  <navigation-case>
    <from-outcome>view</from-outcome>
    <to-view-id>#{sessionScope['javax.portlet.faces.viewIdHistory.view']}</to-view-id>
  </navigation-case>
</navigation-rule>

Linking to Facelets page within same Portlet

When linking to any Facelets page within your portlet web application, you may use the following:

<h:outputLink value="#{facesContext.externalContext.requestContextPath}/home.xhtml">
  <f:param name="javax.portlet.faces.ViewLink" value="true"/>
    navigate to the test page
  </h:outputLink>

Redirect to External Page or Resource

To link to a non JSF View (such as jboss.org), you may use the following:

<h:commandLink actionListener="#{yourBean.yourListener}">
  <f:param name="javax.portlet.faces.DirectLink" value="true"/>
    navigate to the test page
</h:commandLink>

With a backing Bean that has the following:

public class YourBean {
  public void yourListener() {
    FacesContext.getCurrentInstance().getExternalContext().redirect("http://www.jboss.org");
  }
}

renderURL

Using the renderURL tag it's possible to generate a Portlet Render URL that would enable switching between Portlet Modes, such as this:

<pbr:renderURL var="renderUrl" portletMode="edit">
</pbr:renderURL>
<h:outputLink value="#{renderUrl}">Edit Mode</h:outputLink>

namespace

The namespace is particularly useful for prefixing JavaScript functions within a given portlet to ensure that the JavaScript function name doesn't clash with a name from another portlet, or from the same portlet displayed on the same page multiple times. An example for defining a JavaScript method is:

<script type='text/javascript'>
  function <pbr:namespace />DoSomething() {
  }
</script>

Artifacts

First is to add the following dependency to your pom.xml to add the portlet integration library for CDI:

<dependency>
    <groupId>org.gatein</groupId>
    <artifactId>cdi-portlet-integration</artifactId>
    <version>1.0.0.Final</version>
</dependency>

<dependency>
    <groupId>org.gatein</groupId>
    <artifactId>cdi-portlet-integration</artifactId>
    <version>1.0.0.Final</version>
    <scope>provided</scope>
</dependency>

Portlet Filter

Add the following portlet filter definition into your portlet.xml:

<filter>
    <filter-name>PortletCDIFilter</filter-name>
    <filter-class>org.gatein.cdi.PortletCDIFilter</filter-class>
    <lifecycle>ACTION_PHASE</lifecycle>
    <lifecycle>EVENT_PHASE</lifecycle>
    <lifecycle>RENDER_PHASE</lifecycle>
    <lifecycle>RESOURCE_PHASE</lifecycle>
</filter>

Then add to portlet.xml the activation of the above filter for each portlet that requires CDI:

<filter-mapping>
    <filter-name>PortletCDIFilter</filter-name>
    <portlet-name>[Name of your portlet as defined in portlet-name]</portlet-name>
</filter-mapping>

Transient Conversations

Any beans that are defined as @ConversationScoped, but which remain transient, that store data during the ActionRequest will not have that data accessible within the bean during a subsequent RenderRequest. As the Portlet lifecycle uses separate servlet requests to represent ActionRequest and RenderRequest, it results in the conversation context being deactivated at the end of ActionRequest and all transient conversations are destroyed.

Long Running Conversations

The only difference in behavior between a JSF2 application and a JSF2 portlet is that there can be problems if a long running conversation is ended within a RenderRequest.

For example, when a long running conversation is ended during RenderRequest CDI will destroy the conversation at the end of the JSF render response phase, but the id of the conversation will still be present within the Portlet Bridge scope. As the id of the conversation is retained by the Portlet Bridge, if the user refreshes the portlet page and a RenderRequest is sent to the portlet, the previously saved conversation id will be attempted to be activated by CDI but the associated conversation context does not exist.

One work around for the above problem is to not end a long running conversation. Instead of always calling begin() on the injected conversation, only call it when isTransient() is true. This will prevent a failure in converting a transient to long running conversation.

If it's possible for your portlet to only end a long running conversation within an ActionRequest, then you won't experience the above problem.

Ajax calls

As the conversation id parameter, cid, is set as a request parameter on the url, each time we convert a conversation from long running to transient, or vice versa, we need to ensure that any urls that our portlet uses are updated. This ensures that the latest value for the conversation id parameter, or lack of one if we converted a conversation to transient, are present on any links the user clicks. Not doing so can result in problems such as:

• Long running conversations being lost because the conversation id parameter was not present on subsequent requests to the portlet

• A CDI container throwing ContextNotActiveException because the conversation id parameter that was present on the link is no longer present as a valid conversation for use.

In most cases its simply a matter of adding more ids to the render attribute of any ajax component that will start or end a long running conversation, so that the ids of all components that contain url links to actions using a conversation or links to pages of the portlet are included in the list to be re rendered.